After completing this lesson, you’ll be able to:
Annotation is a crucial method for a clear and understandable design.
Annotation helps other users understand what is supposed to be happening in the translation and helps the creator when returning to a workspace after a long interval (take it from me that this is especially important!)
You can apply three different types of annotation to a workspace.
Custom annotation is a comment created by the user. It can be connected to a workspace object (transformer or feature type), connected to a workspace connection, or can float freely within the workspace.
To create an attached custom annotation, right-click a canvas object and select Add Annotation, or use the shortcut Ctrl+K when the object is selected.
To create a floating custom annotation, right-click the canvas, select Insert Annotation, or press Ctrl+K when nothing is selected.
When you place an annotation, you can change the font style, font size, and background color; you can also add hyperlinks, bullet points, and tables.
You might ask: "Why would I use annotation when I can just rename my transformers to make their function more explicit?" This is a good question! Some FME users like to rename transformers to describe what they are doing. However, we've seen some things that could be improved with this approach. First, it's hard to fit enough description in a short name. Second, other users (or yourself in the future) will have yet to learn what the original transformer was and will likely have to open it to see how it is configured. Ultimately, this method saves a little time, but you and your organization can decide if you prefer it.
Summary annotation is an FME-generated comment providing information about any workspace object. This item can be a source or destination feature type or a transformer.
The summary annotation is permanently blue to distinguish it from other annotations. It's always connected to the item it relates to and cannot be detached.
The nice thing about Summary Annotation is that it automatically updates in response to changes. That makes it very useful for checking transformer parameters (or reader/writer schemas) at a glance. It's beneficial when the parameters are set through a wizard and are more awkward to check (for example, the SchemaMapper or FMEServerJobSubmitter transformers).
As of FME 2024.1, you can enhance your ability to document and understand your data workflows by allowing context-specific annotations directly within Parameter Editor dialogs. This ensures that relevant information is continuously visible without cluttering the workspace.
Anywhere you set a parameter via text or in a table, look for the Add Annotation option to add an explanation for why you configured the parameter this way:
Parameter annotation appears in summary annotation, so you can use it as a way to add custom comments while still taking advantage of summary annotation's automatic update features.
You should use summary annotation to show your actions and custom annotation to clarify why you are taking those actions. A good example is when you are not using default values for a transformer or feature type.
Use summary or custom annotation to call out details you wish to be available at a high level, i.e., directly on the canvas. Use parameter annotation for more complex or specific explanations of specific parameter values.
You can convert a summary annotation to a custom annotation by using this context menu option:
This method allows you to extract the information from a summary annotation but edit it as a custom annotation. Note, however, that a converted summary annotation no longer updates automatically!
Now that Jennifer has reminded herself how the workspace works and started to clean it up, she wants to document it with annotation. That way she or her colleagues can get up to speed faster next time they open the workspace.
She opens the starting workspace (C:\FMEData\Workspaces\UseDataIntegrationBestPractices\annotate-your-workspaces.fmw) in FME Workbench (2025.0.1 or later).
Jennifer wants to add annotation to highlight what is happening. This step will require inspecting the transformers to determine what they are doing and inspecting the readers to determine which format they are in.
Add annotation to relevant transformers, for example:
Adding explanatory annotation where necessary will help determine what is happening in the workspace.
The final calculation of the walkability score will get a bit complex, so Jennifer would like to pay particular attention to annotation in that section of the workspace. She'd like to make the noise zone score calculation step more transparent.
She finds the AttributeValueMapper_2 at the far right of the workspace, where the noise zone score is calculated:
She double-clicks it to open its parameters.
Then she clicks the drop-down arrow next to NoiseZoneScore and chooses Add Annotation:
She enters
Impact of noise zones on walkability score, ranging from 50 (high noise) to 200 (low noise).
Then she clicks OK.
She confirms the parameter annotation exists by mousing over the new blue icon:
She clicks OK to close the AttributeValueMapper_2's dialog.
Finally, Jennifer would like to use some summary annotation to show the categories used in the noise zone score.
She right-clicks AttributeValueMapper_2 and chooses Show Summary Annotation:
The summary annotation appears, including the mapping table and the new parameter annotation she just added:
Now Jennifer's workspace is more understandable at a glance.
However, it's missing a visual hierarchy - it's hard to tell which sets of transformers are conducting related tasks. So, now she needs to add some bookmarks.
